.TH BSD n 0.0 "Tcl-Extensions"
.HS BSD tcl
.BS
.SH NAME
BSD \- Tcl interface to various BSD UNIX functions
.SH SYNOPSIS
\fB::bsd::getloadavg\fR 
.br
\fB::bsd::rlimit \fIget|set soft|hard limitName ?val?\fR
.br
\fB::bsd::rusage\fR
.br
\fB::bsd::setproctitle \fIstring\fR
.br
\fB::bsd::statfs \fI path\fR
.br
\fB::bsd::getfsstat \fI?-wait|-nowait?\fR
.br
\fB::bsd::syslog open \fIident logopt facility\fR
.br
\fB::bsd::syslog close\fR
.br
\fB::bsd::syslog logmask \fIpriority\fR
.br
\fB::bsd::syslog log \fIpriority message\fR
.br
\fB::bsd::abort\fR
.br
.SH DESCRIPTION
The BSD extension provides Tcl programs with new Tcl commands to interface
to various system calls and library routines present in BSD UNIX.
.PP
\fB::bsd::getloadavg\fR returns the number of processes in the system
run queue as a list, representing averages over the last 1, 5, and 15
minutes.
.PP
\fB::bsd::rlimit\fR lets you get and set the current soft and hard settings 
for resource limits.  You can specify a 64-bit integer value for any of the
limits or \Bunlimited\fR to indicate that there should be no limit.
.PP
See the Berkeley manpage for \fIgetrlimit\fR and \fIsetrlimit\fR
for details on the options available and what they do.
.PP
\fB::bsd::rusage\fR returns the cumulative resource usage for the current
process, as a list of key-value pairs, suitable for loading into an array
using \fIarray set\fR.  Resources listed include user CPU, system CPU,
max resident set size, shared text Kbyte seconds, unshared data Kbyte
seconds, statck Kbyte seconds, page reclaims, page faults, number of times
swapped, number of file system inputs and outputs, number of interprocess
communications (IPC) messages sent and received, number of signals
delivered, number of voluntary context switches, and number of involuntary
context switches.  For more information see the BSD \fIgetursage\fR manpage.
.PP
\fB::bsd::setproctitle\fR sets the process title that appears on the \fIps\fR
command.  The title is set from the executable's name, followed by the
specified string.  If the string argument begins with a dash characters,
the executable's name is skipped.  If no string is specified, the process
title is restored.  For more information see the BSD \fIsetproctitle\fR
manpage.
.PP
\fB::bsd::statfs\fR returns information about a mounted filesystem.
The \fIpath\fR argument is the path name of any file within the mounted
filesystem.  Results are returned as a list of key-value pairs suitable
for loading into an array using \fIarray set\fR.  Values returned include
the fundamental filesystem block size (\fIfundamentalFileSystemBlockSize\fR), 
the optimal transfer block size (\fIoptimalTransferBlockSize\fR),
the total number of data blocks (\fItotalDataBlocks\fR), the total number of 
free blocks (\fIfreeBlocks\fR), and
the total number of available free blocks (\fIavailableFreeBlocks\fR). 
Also included are the total number of filesystem nodes (\fItotalFileNodes\fR)
and the free file nodes (\fIfreeFileNodes\fR), the file system 
type (\fIfileSystemType\fR), mount point (\fImountPoint), and mounted 
filesystem name (\fImountedFileSystem\fR).  Finally a list of flags is 
provided, which can include \fBreadOnly\fR, \fBsynchronous\fR,
\fBnoExec\fR, \fBnoSUID\fR, \fBnoDev\fR, \fBunion\fR, \fBasynchronous\fR,
\fBSUIDdir\fR, \fBsoftUpdates\fR, \fBnoFollowSymlinks\fR, \fBnoAtime\fR,
\fBnoClusterRead\fR, \fBnoClusterWrite\fR, \fBexportReadOnly\fR,
\fBexported\fR, \fBworldExported\fR, \fBanonUidMapping\fR,
\fBkerberosUidMapping\fR, \fBwebNFS\fR, \fBfilesystemStoredLocally\fR,
\fBquotasEnabled\fR, \fBrootFilesystem\fR, \fBuserMounted\fR, \fBmultiLabel\fR,
and \fBaclsEnabled\fR.
.PP
\fB::bsd::getfsstat\fR functions like \fBstatfs\fR, except that it returns
a list of lists with information about all mounted filesystems.  If
\fI-nowait\fR or no option is specified, \fBgetfsstat\fR will directly return
the filesystem information retained in the kernel to avoid delays caused
by waiting for updated information from a filesystem that is perhaps
temporarily unable to respond, at the cost of the data perhaps not reflecting
the absolutely current status of the filesystem.  As some of the information 
returned may be out of date, if \fI-wait\fR is specified, \fBgetfsstat\fR will
request updated information for each mounted filesystem prior to returning.
.PP
\fB::bsd::syslog\fR provides a direct interface to the syslog library
to provide a way to write messages into the system log.  
\fB::bsd::syslog open\fR takes an identifier, a list of zero or more
\fIlog options\fR, and a facility name.
The facility name can be one of \fBauth\fR, \fBauthpriv\fR, \fBconsole\fR,
\fBcron\fR, \fBdaemon\fR, \fBftp\fR, \fBkern\fR, \fBlpr\fR, \fBmail\fR,
\fBnews\fR, \fBntp\fR, \fBsecurity\fR, \fBsyslog\fR, \fBuser\fR, \fBuucp\fR,
\fBlocal0\fR, \fBlocal1\fR, \fBlocal2\fR, \fBlocal3\fR, \fBlocal4\fR,
\fBlocal5\fR, \fBlocal6\fR, or \fBlocal7\fR.
.PP
Log options can include \fBconsole\fR, which causes the message to be
logged on the console if there are errors in sending it, \fBno_delay\fR,
which theoretically says not to delay opening the syslog connection until
the first syslog call is made, but check your documentation on syslog(3)
to see if that's really true, \fBpid\fR, which says to log the process
ID along with whatever else, and \fBperror\fR, which says to log the
message to stderr as well as to the system log.
.PP
\fB::bsd::syslog log\fR takes a priority and a message.
Priority can be one of 
\fBemerg\fR, \fBalert\fR, \fBcrit\fR, \fBerr\fR, \fBwarning\fR, 
\fBnotice\fR, \fBinfo\fR, or \fBdebug, in descending order of priority.
Check your documentation on your syslog library, high priority messages
do stuff besides logging, like blasting to all logged in users, while
\fB::bsd::syslog close\fR closes the connection to the system log.
Finally, .fB::bsd::syslog logmask\fR sets the log priority mask and masks all priorities
up to and including the specified one.  For instance, if you invoked
the logmask option with the \fBinfo\fR priority, both \fIinfo\fR and
\fIdebug\fR log messages would be suppressed.
.PP
\fB::bsd::abort\fR causes abnormal program termination to occur by issuing
an abort signal and will work unless the SIGABRT signal is being caught
and the signal handler does not return.
